Developing web services using the HTTP connector

This topic describes the procedure to develop web services using HTTP connector with the Delicious Bookmarks service.

Using REST with HTTP Connector

You must create a new CWS project which uses the HTTP connector to integrate with the Delicious Bookmarks service. The Delicious API is a REST-based API that accepts GET requests on specific URLs with certain URL parameters. Basic authentication is required for updating. Some REST-based services use PUT, POST, and DELETE for updating, adding, and deleting, whereas the Delicious API uses the GET command for updating and also deleting.

The following example uses the v2 feeds API. See http://delicious.com/help/feeds for more information.

Setting up a basic CWS project

Create a new CWS project in which you want to use the HTTP connector.
In the CWS project, add a Runtime Reference to the HTTP connector as follows:
1. Create a new folder Runtime Reference in the project.
2. In this folder add a run-time reference to an application connector.
3. From the folder OpenText HTTP Connector, select OpenText HTTP Connector.
Add HttpConnector configuration as follows:

Note: In run time, HTTP connector searches for configuration in the XML store under OpenText/HttpConnector path. Hence, it is important to define the XML store path correctly in the CWS.
1. Create a folder XML Store.
2. Right-click XML Store and select Set Start Point of Qualified Name_Make.
3. In the XML Store folder, add a XML Store Definition and name it HttpConnector Config.
4. Create a folder OpenText in the XML Store folder.
5. Open the OpenText folder and add a sub-folder HttpConnector.
6. Open HttpConnector folder and add the XML object config.xml. This object contains the actual HTTP connector configuration.
7. Add the following HTTP configuration and save the XML object.

<configurations xmlns="http://httpconnector.opentext.com/1.0/configuration">
    <connections>
        <connection id="CONN-DELICIOUS-FEED">
            <url>http://feeds.delicious.com</url>
        </connection>
    </connections>
</configurations>

The namespace for the HTTP connector configuration is http://httpconnector.opentext.com/1.0/configuration. It is added as the default namespace on the configuration tag.

The configuration includes one connection with the ID CONN-DELICIOUS-FEED.

The following parameters are used in the HTTP connector connection configuration:

Parameter	Description
@id	It is an attribute of the connection tag. Refers to the name of the connection.
url	Refers to the server endpoint URL. It can include a part or the complete URL of the service endpoint.
authenticate-always	Always sends the authentication information, also known as Preemptive Authentication. This is optional and the default value is false.
check-certificate	Used with HTTPS connections only. It can be used as an option to check the SSL certificate. In a test environment, you can choose to ignore any errors while validating the SSL certificate. When it is set to false, any certificate that is either valid or invalid, expired, or not expired is accepted. This is optional and the default value is false.
username	Refers to the username used for authentication at the service endpoint. This is optional.	w
password	Refers to the password in base64 encoding, used for authentication at the service endpoint. This is optional.
timeout	HTTP request timeout value in milliseconds. This is optional and the default value is 30000 (30 seconds).

Creating a web service using the HTTP connector

Available handlers

The following diagram shows the various handlers available in the HTTP connector and the XML for the parameters in implementation.

This is a sample implementation XML and the related explanation on how the extended handlers reuse the implementation XML from the super or generic handlers, and how to configure such implementation XML to leverage the functionality of multiple handlers.

HTTP Get request without parameters

To add a web service to the CWS project:

Create a folder Web Services.
Add a web service and use Custom Web Service at Select the source.
Name the web service with a name such as DeliciousRestServices.
Provide Description same as the name.
Provide a Namespace.
Enter DeliciousRestServices as the Web Service Interface Name.
Select the OpenText HTTP Connector for the Implementation Class.
Add a web service operation GetBookMarksWithFixedUri.
Open GetBookMarksWithFixedUri and paste the following XML in the implementation field.

<implementation type="HTTP" xmlns="http://httpconnector.opentext.com/1.0/implementation" xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
    <connection-id>CONN-DELICIOUS-FEED</connection-id>
    <uri>/v2/rss/cordysrest</uri>
    <http-method>GET</http-method>
    <request-handler class="com.opentext.applicationconnector.httpconnector.impl.RestRequestHandler"/>
    <response-handler class="com.opentext.applicationconnector.httpconnector.impl.StandardResponseHandler"/>
    <valid-response-code>200</valid-response-code>
    <namespaces/>
</implementation>

The above XML is used to configure CONN-DELICIOUS-FEED connection.

Parameter	Description
uri	Contains the additional URL of the service endpoint. The service endpoint is a concatenation of the `connection-id` URL and the URI.
http-method	Used for GET method. Note: HTTP connector also supports POST, PUT, and DELETE.
request-handler class	The `RestRequestHandler` builds the correct REST request.
response-handler class	The `StandardResponseHandler` returns the response XML.
valid-response-code	Used to check if the HTTP response code is a valid one. This indicates whether the request was successful or not.
namespace	Left empty and not used with the `RestRequestHandler.`

Execute the web service

To execute the GetBookMarksWithFixedUri web service:

Publish the CWS project. With Publish to Runtime option of the project, HTTP Configuration XML is added to the XML store.
Create a new HTTP Service Group and service container using System Resource Manager, if it doe not exist. In OpenText HTTP Connector configuration , add the file path config.xml in the XMLStore Configuration File Path field.
Start the HTTP connector to load the configuration. Note: After changing and publishing a web service implementation, use the Reset option to clear the internal method definition cache of the HTTP connector
Right-click on the web service operation and test the web service operation with Test Web Service Operation().
The Operation Test Tool appears with a SOAP request for the GetBookmarksWithFixedUri web service operation.
Invoke the operation. The HTTP connector calls the Delicious Rest service to get the Bookmarks for the user cordysrest.

Example SOAP request

<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP:Body>
        <GetBookmarksWithFixedUri xmlns="http://com.opentext.delicious/rest"/>
    </SOAP:Body>
</SOAP:Envelope>

Example SOAP response

<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP:Body>
        <GetBookmarksWithFixedUriResponse xmlns="http://com.opentext.delicious/rest" xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:cc="http://web.resource.org/cc/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:wfw="http://wellformedweb.org/CommentAPI/">
            <channel>
                <title>Delicious/cordysrest</title>
                <link>http://www.delicious.com/cordysrest</link>
                <description>links posted by cordysrest</description>
                <link href="http://feeds.delicious.com/v2/rss/cordysrest" rel="self" type="application/rss+xml"/>
                <item>
                    <title>Dropbox - Home - Online backup, file sync and sharing made easy.</title>
                    <pubDate>Mon, 10 Oct 2011 12:50:03 +0000</pubDate>
                    <guid isPermaLink="false">http://www.delicious.com/url/1efb6ae3c567e43fc1330522b718b167#cordysrest</guid>
                    <link>http://www.dropbox.com/</link>
                    <creator><![CDATA[cordysrest]]></creator>
                    <comments>http://www.delicious.com/url/1efb6ae3c567e43fc1330522b718b167</comments>
                    <commentRss>http://feeds.delicious.com/v2/rss/url/1efb6ae3c567e43fc1330522b718b167</commentRss>
                    <source url="http://feeds.delicious.com/v2/rss/cordysrest">cordysrest&apos;s links</source>
                    <description>
                        <p/>
                    </description>
                    <category domain="http://www.delicious.com/cordysrest/">cloud</category>
                </item>
                <item>
                    <title>mobilebetalen</title>
                    <pubDate>Mon, 10 Oct 2011 12:42:47 +0000</pubDate>
                    <guid isPermaLink="false">http://www.delicious.com/url/93e9c587e8653329285c22e01171d587#cordysrest</guid>
                    <link>http://www.mobilebetalen.nl/</link>
                    <creator><![CDATA[cordysrest]]></creator>
                    <comments>http://www.delicious.com/url/93e9c587e8653329285c22e01171d587</comments>
                    <commentRss>http://feeds.delicious.com/v2/rss/url/93e9c587e8653329285c22e01171d587</commentRss>
                    <source url="http://feeds.delicious.com/v2/rss/cordysrest">cordysrest&apos;s links</source>
                    <description>
                        <p/>
                    </description>
                    <category domain="http://www.delicious.com/cordysrest/">mobile</category>
                </item>
                <item>
                    <title>Cordys Professionals Cloud</title>
                    <pubDate>Mon, 10 Oct 2011 12:50:26 +0000</pubDate>
                    <guid isPermaLink="false">http://www.delicious.com/url/ff62b7af01ef3b275a2a7bf770efada3#cordysrest</guid>
                    <link>http://community.cordys.com/</link>
                    <creator><![CDATA[cordysrest]]></creator>
                    <comments>http://www.delicious.com/url/ff62b7af01ef3b275a2a7bf770efada3</comments>
                    <commentRss>http://feeds.delicious.com/v2/rss/url/ff62b7af01ef3b275a2a7bf770efada3</commentRss>
                    <source url="http://feeds.delicious.com/v2/rss/cordysrest">cordysrest&apos;s links</source>
                    <description>
                        <p/>
                    </description>
                    <category domain="http://www.delicious.com/cordysrest/">cordys</category>
                    <category domain="http://www.delicious.com/cordysrest/">cloud</category>
                </item>
                <item>
                    <title>http://ww.cordys.com/</title>
                    <pubDate>Mon, 10 Oct 2011 12:46:11 +0000</pubDate>
                    <guid isPermaLink="false">http://www.delicious.com/url/541dcd5ab16ef7e01712cdc9a8b53eb1#cordysrest</guid>
                    <link>http://ww.cordys.com/</link>
                    <creator><![CDATA[cordysrest]]></creator>
                    <comments>http://www.delicious.com/url/541dcd5ab16ef7e01712cdc9a8b53eb1</comments>
                    <commentRss>http://feeds.delicious.com/v2/rss/url/541dcd5ab16ef7e01712cdc9a8b53eb1</commentRss>
                    <source url="http://feeds.delicious.com/v2/rss/cordysrest">cordysrest&apos;s links</source>
                    <description>
                        <p/>
                    </description>
                    <category domain="http://www.delicious.com/cordysrest/">cordys</category>
                </item>
                <item>
                    <title>Delicious.com - Discover Yourself!</title>
                    <pubDate>Mon, 10 Oct 2011 12:10:24 +0000</pubDate>
                    <guid isPermaLink="false">http://www.delicious.com/url/c8287f6a93d2d80051d2142bae4139d6#cordysrest</guid>
                    <link>http://www.delicious.com/cordysrest/</link>
                    <creator><![CDATA[cordysrest]]></creator>
                    <comments>http://www.delicious.com/url/c8287f6a93d2d80051d2142bae4139d6</comments>
                    <commentRss>http://feeds.delicious.com/v2/rss/url/c8287f6a93d2d80051d2142bae4139d6</commentRss>
                    <source url="http://feeds.delicious.com/v2/rss/cordysrest">cordysrest&apos;s links</source>
                    <description>
                        <p/>
                    </description>
                </item>
            </channel>
        </GetBookmarksWithFixedUriResponse>
    </SOAP:Body>
</SOAP:Envelope>

HTTP Get request with parameters service URI

The above example has a fixed service URI in the web service operation.

To add a new web service operation:

Select Add/Update operations on the Delicious Rest Services web service.
From Select the source, select Custom Web Service.
Select the Overwrite to existing Web Service Interface check box and select Delicious Rest Services web service.
Add a new Web Service Operation and name it GetBookmarksForUser.
Add the below Web Service Operation implementation.
Publish the web service Delicious Rest Services to organization
Reset the HTTP connection service container.
Test the new web service operation GetBookmarksForUser.

GetBookmarksForUser implementation:

<implementation type="HTTP" xmlns="http://httpconnector.opentext.com/1.0/implementation" xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
    <connection-id>CONN-DELICIOUS-FEED</connection-id>
    <http-method>GET</http-method>
    <uri>/v2/rss/{0}</uri>
    <request-handler class="com.opentext.applicationconnector.httpconnector.impl.RestRequestHandler">
        <uri-parameters>
            <parameter type="xpath">./Username</parameter>
        </uri-parameters>
    </request-handler>
    <response-handler class="com.opentext.applicationconnector.httpconnector.impl.StandardResponseHandler"/>
    <valid-response-code>200</valid-response-code>
    <namespaces/>
</implementation>

The URI parameter formats the URI according to the given format. For example /v2/rss/{0} or /project/{0}/task/{1}. The parameters {0}, {1}, and so on are filled with the parameters included in the URI parameters. Note: The connection URI parameters start at 0.

Example SOAP request

<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP:Body>
        <GetBookmarksForUser xmlns="http://com.opentext.delicious/rest">
            <Username>cordysrest</Username>
        </GetBookmarksForUser>
    </SOAP:Body>
</SOAP:Envelope>

On execution of the above web service operation, the value of the Username tag is used as a URL parameter.

Following is another example of using the URI parameters. Read a URL such as:

http://feeds.delicious.com/v2/rss/cordysrest/cloud+cordys

Add it as web service operation GetBookmarksForUserWithMultiLevelInput:

<implementation type="HTTP" xmlns="http://httpconnector.opentext.com/1.0/implementation" xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
    <connection-id>CONN-DELICIOUS-FEED</connection-id>
    <http-method>GET</http-method>
    <uri>/v2/rss/{0}/{1}</uri>
    <request-handler class="com.opentext.applicationconnector.httpconnector.impl.RestRequestHandler">
        <uri-parameters>
            <parameter type="xpath">./Username</parameter>
            <parameter type="xpath">./Tags/Tag</parameter>
        </uri-parameters>
    </request-handler>
    <response-handler class="com.opentext.applicationconnector.httpconnector.impl.StandardResponseHandler"/>
    <valid-response-code>200</valid-response-code>
    <namespaces/>
</implementation>

SOAP request

<SOAP:Envelope xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP:Body>
        <GetBookmarksForUserWithMultiLevelInput xmlns="http://com.opentext.delicious/rest">
            <Username>cordysrest</Username>
            <Tags>
                <Tag>cloud</Tag>
            </Tags>
        </GetBookmarksForUserWithMultiLevelInput>
    </SOAP:Body>
</SOAP:Envelope>

HTTP Put/Post request

Note: The steps to be followed to create a web service operation for HTTP Put/Post are same as those for HTTP Get.

The request handler to be used in the web service operation implementation is based on the service type, for example, for standard web services use com.opentext.applicationconnector.httpconnector.impl.StandardRequestHandler or for REST services use com.opentext.applicationconnector.httpconnector.impl.RestRequestHandler. The request handler picks up the content of the SOAP request, XML node below the SOAP body, and applies necessary transformation and put it inside the HTTP request body.

HTTP Delete request

Note: The steps to be followed to create a web service operation for HTTP Delete including the request and response handlers that are applicable are exactly the same as those for HTTP Get.

Transforming request and response using XSLT

To specify request and response XSLTs:

Create XSLT files in a folder and store the XSLT files under XML store as XML.
Provide the paths of the XML files in the web service operation implementation.
The request XSLT is applied to the incoming SOAP request and the output of the transformation is put inside the HTTP request body.
Note: This is applicable only to HTTP Put and Post as these are the requests that can contain a payload in the request body.
The response XSLT is applied to the HTTP response received and the output of the transformation is put inside the SOAP response under the SOAP Body element.
Note: This is applicable to all the four HTTP request methods (Get,Put,Post, and Delete) supported by the HTTP connector.

A web service operation implementation with request XSLT and response XSLT specified is as follows:

<implementation type="HTTP" xmlns="http://httpconnector.opentext.com/1.0/implementation">
    .....................................................................................
	.....................................................................................
    <request-handler class="com.opentext.applicationconnector.httpconnector.impl.StandardRequestHandler">
        <xslt xmlstore="xslts/requestXSLT.xml"/>
    </request-handler>
    <response-handler class="com.cordys.coe.ac.httpconnector.impl.StandardResponseHandler">
        <xslt xmlstore="xslts/responseXSLT.xml"/>
    </response-handler>
</implementation>

Handling JSON as input and output parameters of REST service

JSON is an open standard format used to transfer data between a web-based application or service and server and is very popular as an alternative to XML data format in the web. JSON objects, in the form of attribute-value pairs, can be used as an input to a web service and the response of the web service can be in the JSON format.

Using HTTP connector, you can invoke web service which accepts JSON objects as input or the web service which returns the JSON objects. For HTTP GET request, there is no change in the request format.

In case of HTTP POST request, set Content-Type as 'application/json' in the header part of RestRequestHandler as follows:

<implementation xmlns="http://httpconnector.opentext.com/1.0/implementation" xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/" type="HTTP">
........................
	<connection-id>JSON-TEST</connection-id>	
	<request-handler class="com.opentext.applicationconnector.httpconnector.impl.RestRequestHandler">
		<req-headers>
			<header name="Content-Type">application/json</header>
		</req-headers>		
	</request-handler>
	<response-handler class="com.opentext.applicationconnector.httpconnector.impl.RestResponseHandler"/>
	<valid-response-code>200</valid-response-code>
	
................
</implementation>

Note: If it is a JSON response, then the HTTP connector transforms that to XML before sending it to the caller.

Using authentication

The HTTP connector only supports basic authentication. The Delicious service also has services that require authentication. In fact, all V1 services need it.

Test with the service URL: https://www.delicious.com/v1/posts/all. Also, note the services that are using https.

Update the connection configuration and add a new connection.

The new configuration is given below:

<configuration mxmlns="http://httpconnector.opentext.com/1.0/configuration">
    <connections>
        <connection id="CONN-DELICIOUS-FEED">
            <url>http://feeds.delicious.com</url>
        </connection>
        <connection id="CONN-DELICIOUS">
            <url>https://www.delicious.com</url>
            <username>cordysrest</username>
            <password>UmVzdFdpdGhDb3JkeXM=</password>
            <authenticate-always>true</authenticate-always>
            <check-certificate>false</check-certificate>
        </connection>
    </connections>
</configuration>

Note: Restart the HTTP connector service container to load the new configuration.

The web service operation for GetPostsWithAuth is as follows:

<implementation type="HTTP" xmlns="http://httpconnector.opentext.com/1.0/implementation" xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/">
    <connection-id>CONN-DELICIOUS</connection-id>
    <http-method>GET</http-method>
    <uri>/v1/posts/get</uri>
    <request-handler class="com.opentext.applicationconnector.httpconnector.impl.RestRequestHandler"/>
    <response-handler class="com.cordys.coe.ac.httpconnector.impl.StandardResponseHandler"/>
    <valid-response-code>200</valid-response-code>
    <namespaces/>
</implementation>

Adding custom HTTP headers

Many REST APIs expect custom HTTP request headers. Few examples are as follows:

REST Service Provider	Custom Headers	Value
Azure	x-ms-version	2011-08-18
Google Data API	GData-Version	X.0
Tibbr API (Authenticated Session)	client_key	[ applicable value]
	auth_token	[ applicable value]

The custom HTTP headers can be set by configuring the <implementation> for <req-headers> as follows:

 <implementation xmlns="http://httpconnector.opentext.com/1.0/implementation" xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/" type="HTTP">
  <connection-id>AZURE_MANAGEMENT</connection-id>
  <uri>/{0}/services/hostedservices/{1}/deployments/{2}/roles</uri>
  <http-method>POST</http-method>
  <request-handler class="com.opentext.applicationconnector.httpconnector.impl.RestRequestHandler">
    <uri-parameters>
      <parameter type="connection-parameter">subscriptionID</parameter>
      <parameter type="xpath">ServiceName</parameter>
      <parameter type="xpath">DeploymentName</parameter>
    </uri-parameters>
    <req-headers>
      <header name="x-ms-version">2012-03-01</header>
      <header name="Content-Type">application/xml</header>
    </req-headers>
    <root-xpath>./PersistentVMRole</root-xpath>
  </request-handler>
 
  <valid-response-code>201</valid-response-code>
  <namespaces>
    <binding prefix="ns" uri="http://schemas.microsoft.com/windowsazure" />
  </namespaces>
</implementation>

Organization awareness

When HTTP connector is configured in the system organization, it becomes organization-aware. The behavior of the the HTTP connector running in the system organization is as follows:

The HTTP connector configuration file is read from the organization of the user sending the request.
- If the configuration file does not exist in the organization space, then it is picked up from the shared (ISV) space.
The XSLTs is read from the organization of the user sending the request.
- If the XSLT does not exist in the organization space, then it is picked up from the shared (ISV) space.

When HTTP connector is configured in any other organization, then the configuration files and the XSLTs are picked up from the organization in which the service container is running. If not found in the organization space, the HTTP connector searches for the files in the shared (ISV) space.

Common errors

IllegalOperationException: Prefix and/or URI cannot be NULL. [addNamespaceBinding:166]

Solution: You do not have a default namespace on the configuration or implementation. Ensure that you have the following :

<implementation xmlns="http://httpconnector.opentext.com/1.0/implementation"
 xmlns:SOAP="http://schemas.xmlsoap.org/soap/envelope/" type="HTTP">

Sample projects

Title

CWS Project

Remark

Norwegian Weather API - REST Client

Norwegian Weather API.zip

Purpose: To help new developers to quickly get started with using the HTTP connector to consume external REST services.

Ensure not to violate the Conditions for use of the service.
The project imports and thus implicitly also demonstrates the usage of external XML schema to create proper wsdl for the web service generated over external REST API.
It also includes samples for (GetAlmanac.xml under the project folder: /src/test/)
- SOAP request and response.
- HTTP connector configuration file for connection details - The path can be configured as available in the GetAlmanac.xml.
It is assumed that the developer has basic knowledge of:
- synchronizing the project content into applicable workspace.
- setting the service group property for the custom web services on the 'Web Service Binding Properties' form.
- publishing the project to organization.

pp108 : Developing web services using the HTTP connector

Developing web services using the HTTP connector

Setting up a basic CWS project

Creating a web service using the HTTP connector

Available handlers

HTTP Get request without parameters

Execute the web service

Example SOAP request

Example SOAP response

HTTP Get request with parameters service URI

Example SOAP request

SOAP request

HTTP Put/Post request

HTTP Delete request

Transforming request and response using XSLT

Handling JSON as input and output parameters of REST service

Using authentication

Adding custom HTTP headers

Organization awareness

Common errors

IllegalOperationException: Prefix and/or URI cannot be NULL. [addNamespaceBinding:166]

Sample projects